﻿///////////////////////////////////////////////////////////////////////////////
//
//  This source is part of the  "Managed Task Framework.NET Runtime"  (MTF.NET Runtime).
//
//
//  Copyright (c) 2011, Multicore Consulting Limited (UK)
//  All rights reserved.
//  http://www.multicoreconsulting.co.uk
//
//  Redistribution and use in source and binary forms, with or without
//  modification, are permitted provided that the following conditions
//  are met:
//
//  -  Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//  -  Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in
//     the documentation and/or other materials provided with the
//     distribution.
//  -  Neither the name of Multicore Consulting Limited nor the names of
//     its contributors may be used to endorse or promote products
//     derived from this software without specific prior written
//     permission.
//
//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
//  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
//  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
//  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
//  COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
//  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
//  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
//  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
//  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
//  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
//  POSSIBILITY OF SUCH DAMAGE.
//
///////////////////////////////////////////////////////////////////////////////

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading;

namespace MTFOrg.MTF.MTFRuntime
{
    /// <summary>
    /// Task manager interface.
    /// </summary>
    public interface ITaskManager
    {
        /// <summary>
        /// Asynchronous message send.
        /// </summary>
        /// <param name="newMessage">Message to send</param>
        /// <param name="connection">Connection to send message on</param>
        void QueueMessage(IMessage newMessage, IConnection connection);

        /// <summary>
        /// Asynchronous event send
        /// </summary>
        /// <param name="newMessage">Message to send</param>
        /// <param name="connection">Connection to send event on</param>
        /// <param name="threadIndex">Index of preferred thread for execution</param>
        void QueueMessage(IMessage newMessage, IConnection connection, int threadIndex);

        /// <summary>
        /// Synchronous message send.
        /// </summary>
        /// <param name="newMessage">Message to send</param>
        /// <param name="connection">Connection to send message on</param>
        void SendMessage(IMessage newMessage, IConnection connection);

        /// <summary>
        /// Adds new work to the queue for the worker thread with the lightest load.
        /// </summary>
        /// <param name="waitCallback">Call-back executed by the worker thread</param>
        /// <param name="state">State to pass to the call-back function</param>
        /// <param name="priority">Execution priority of the work item</param>
        void QueueUserWorkItem(WaitCallback waitCallback, object state, int priority);

        /// <summary>
        /// Adds new work to the queue for a specific worker thread.
        /// </summary>
        /// <param name="waitCallback">Call-back executed by the worker thread</param>
        /// <param name="state">State to pass to the call-back function</param>
        /// <param name="priority">Execution priority of the work item</param>
        /// <param name="threadIndex">Index of thread to run task on</param>
        /// <param name="isGui">Whether to run items in the GUI worker pool</param>
        void QueueUserWorkItem(WaitCallback waitCallback, object state, int priority, int threadIndex, bool isGui);

        /// <summary>
        /// Filters out connections that are not allowed.
        /// </summary>
        /// <param name="newConnections">List of requested connections</param>
        /// <returns>List of allowed connections</returns>
        ConnectionList FilterConnections(ConnectionList newConnections);

        /// <summary>
        /// Default prototype validation function always allows connection.
        /// </summary>
        /// <param name="connectionPoints">Points to validate connection for</param>
        /// <returns>true if points can be connected, otherwise false</returns>
        bool CanConnectPoints(IConnectionPoint sourceConnectionPoint, IConnectionPoint targetConnectionPoint);

        /// <summary>
        /// Disposes of the task manager and its resources.
        /// <param name="force">forces workers to abort immediately</param>
        /// </summary>
        void Dispose(bool force = false);

        /// <summary>
        /// Determines if shutdown of the worker threads has completed.
        /// </summary>
        /// <returns>true if shutdown complete, otherwise false</returns>
        bool IsShutdown();

        /// <summary>
        /// Finds the specified interface and returns it.
        /// </summary>
        /// <param name="path">Path of interface to return</param>
        /// <returns>Interface with specified path</returns>
        object FindInterface(string path);

        /// <summary>
        /// Registers the specified interface.
        /// </summary>
        /// <param name="path">Path of interface</param>
        /// <param name="ifceObject">Interface object to register</param>
        void RegisterInterface(string path, object ifceObject);
    }
}
